Generate multiple types, one for each compatibility date that changes type signatures#137
Generate multiple types, one for each compatibility date that changes type signatures#137
Conversation
0c18f4e to
be1df8e
Compare
5359814 to
5cf109d
Compare
30ed347 to
aad867d
Compare
5cf109d to
a8fba03
Compare
|
@mrbbot This should be reviewable |
mrbbot
left a comment
There was a problem hiding this comment.
Awesome! 😃 Added some suggestions. 👍
|
Looks good! ✅ Will approve once #136 is merged. 👍 |
f98a4f6 to
29b7af0
Compare
463ff5f to
f20ad96
Compare
src/workerd/tools/BUILD.bazel
Outdated
| # https://developers.cloudflare.com/workers/platform/compatibility-dates/#global-navigator | ||
| ("2022-08-04", "2022-08-04"), | ||
| # Latest compatibility date | ||
| ("2024-01-01", "experimental"), |
There was a problem hiding this comment.
Maybe push this date a lot further into the future? Also, do we want experimental to enable all flags even those without default on dates, or not?
There was a problem hiding this comment.
I've pushed it to 2030. I don't think we want to enable things without a default on date, because that includes super experimental stuff like nodejs compat
There was a problem hiding this comment.
Maybe experimental is the wrong name then, actually—I had latest before, but that didn't feel sufficiently warning-y
There was a problem hiding this comment.
stabilized could work? We only give default on dates once the flags have stabilised, but again not very warning-y. Let's stick with experimental. 👍
There was a problem hiding this comment.
What's the purpose of this / how does this string get exposed to the customer? My (fuzzy) understanding is that this code will generate type information from enabling all compatibility flags which have enable-dates, and this type information is named "experimental"?
"latest" would make more sense to me, if so. When we assign an enable-date to a compatibility flag, we are saying that the new behavior is now the preferred, stable behavior.
There was a problem hiding this comment.
The issue that we saw with latest was that if someone is using that set of types in their typescript definitions, an update to the package would unexpectedly change their types (because new compatibility flags will be added and integrated into latest/experimental in the future), whereas pinning to a date version will guarantee type consistency as of that default on date. Currently, we think this'll be exposed as a reference to @cloudflare/workers-types/experimental or @cloudflare/workers-types/2022-11-03 in a user's typescript config.
There was a problem hiding this comment.
I think what Harris is saying is call it latest or now instead of experimental. experimental is misleading as to the name of the types. I concur with that.
A separate thing that's going to confuse me as an end user is that @cloudflare/workers-types/2022-11-03 is totally divorced from the compat date in wrangler.toml. In wrangler.toml I can pick any date. In the types I can only pick dates that mean something in the runtime. This is going to be a point of friction and confusion. You may want to make sure the docs are very clear here about guidance (e.g. "make sure that wrangler.toml picks the same date as the types for readability - the list of valid type dates are provided in the compat dates"). Alternatively, if you can provide types for all the dates such that they symlink to the real dates that have type signatures generated, then you can just say "specify the date same as you do in wrangler.toml" without forcing them to reference the (lagging & incomplete) docs to find a specific date that will work for them.
This generates a
bazel-bin/types/definitions/*/api.d.tsandbazel-bin/types/definitions/*/api.tsfile for the following compatibility dates:latest, the current up to date version of the runtime2022-08-04, #r2-bucket-list-respects-the-include-option2022-03-21, #global-navigator2022-01-31, #settersgetters-on-api-object-prototypes2021-11-03, #formdata-parsing-supports-file2021-01-01, before any compatibility date based changesTwo of these dates don't change the types, but I think they should, based on their description (cc @mrbbot):
2022-08-04
2021-11-03